The HTMLRenderingLib provides facilities allowing developers to draw HTML files. The library provides a facility developers can use to display HTML based help content in their applications or application packages.
The HTML rendering library provides HTML rendering objects that do the actual HTML drawing. Routines are provided allowing applications to create and manipultate rendering objects. These objects are referenced through an opaque data type called an HRReference. The actual implementation and details of how the rendering object works and the data it stores are kept hidden from client applictions and the only way to manipulate these objects is by using the routines provided by the library.
Routines are provided for handling events directed at HTML data displayed on the screen. Most of the work required for maintaining an area of the screen set aside for an HTML rendering object is handled by the HTML rendering library in the routine HRIsHREvent. At the very least, in an event handling routine an application will need to call the HTML rendering library in response to update events (by calling HRDraw) and activate events (by calling HRActivate or HRDeactivate).
To speed drawing and redrawing the library maintains a memory based cache of previously viewed images and HTML data. This cache is maintained inside of the application's heap zone and will grow as pages are viewed. Left unchecked, the cache has the potential to grow until the entire heap zone has been consumed. But, it is possible to reclaim some of this storage by calling the HRFreeMemory routine. This routine will release memory occupied by the cache for other uses in an application.
The display characteristics for HTML rendering objects, such as it's location on screen, the GrafPort where the HTML image is to be drawn, the state of the scroll bars, et cetera, can be modified by application clients. Also, a routine is provided that allows applications to query the actual size of the HTML image after it has been drawn by an HTML rendering object.
As one would expect, the HTML rendering library includes a set of routines for directing HTML rendering objects to display URLs and for scrolling the display to specific anchors. Also, it is possible to render HTML data directly from memory rather than using a file. Along with these routines, there are a set of utility routines for manipulating URLs and easily creating URLs that refer to Macintosh files.
For managing visited links, the rendering library allows applications to associate callbacks with HTML rendering objects. The HTML rendering library calls these routines either when it needs to know if a link has been visited or whenever it is moving the display to a new page.
In applications where it is appropriate to provided your own custom URL to Macintosh file mapping scheme, it is possible to associate a callback with a HTML rendering object that the HTML rendering library will call to map URLs to Macintosh files.
HTMLRenderingLib is by no means a full scale HTML environment and should not be used as a general HTML rendering engine. In particular, it should not be used for displaying extreemly large HTML files. Always test the content you intend to display using the HTMLRenderingLib to ensure it will work as expected.
Some of the HTMLRenderingLib routines leave either the grafport's origin or the grafport's clipping region in an undefined state. If you are drawing other objects in the same window that you are using with an html rendering library object, then you should be aware of this and reset these parts of the drawing environment as appropriate before attempting to do any drawing of your own. This sample application handles these cases appropriately.